AWS Systems Manager ディストリビューターによるパッケージ配布の全体像を絵に描いて理解してみた

Systems Manager のサービスを触るたび、いろいろ組み合わさっていて、魔境かよ……という思いに駆られます。

#図解

#EC2 Systems Manager

#AWS Systems Manager（SSM）

#AWS

千葉幸宏（チバユキ）

2020.07.15

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

コンバンハ、千葉（幸）です。

AWS Systems Manager Distributor では、ソフトウェアをパッケージ化し、マネージドインスタンスに対して効率的に配布することができます。配布するパッケージを一元管理することで、複数のインスタンスにおけるソフトウェアのバージョンを統一化したり、ライフサイクルの管理を行うことが可能となります。

この配布は何によって実現されているのか？関連するリソースは何なのか？を絵（というか図）に描き起こしながら理解を深めていったところ、以下が出来上がりました。

はい。

詰め込み過ぎ感がありますね。

図の中に肝心の「ディストリビューター」っていう文字が出てこないじゃん！と自分でも思いましたが、ディストリビューターとは機能であり、概念であり、そしてまた一つの真実であり、常にあなたのすぐ側に寄り添っています。さっそく私たちの親愛なる友人の姿を確認していきましょう。

マネージドインスタンス

ディストリビューターによる配布対象となるのはマネジードインスタンスです。 EC2 インスタンスのほか、オンプレミスのサーバもマネージドインスタンスとすることができます。

マネージドインスタンス内には SSM エージェントが稼働しており、ディストリビューターにより配布されるパッケージのインストール・更新などは SSM エージェントによって行われることとなります。

マネージドインスタンスとして Systems Manager の管理対象となるにはいくつか条件が必要ですが、特に重要な点は以下の通りです。

SSM エージェントが導入されていること
SSM エンドポイントに疎通可能であること
EC2 インスタンスの場合 IAM インスタンスプロファイルがアタッチされ必要な権限が付与されていること

詳細は以下を参照してください。

ディストリビューターによる配布の対象となるインスタンスは、以下のような方式で選択することができます。

インスタンス ID で個別に指定
付与されているタグで指定
リソースグループで指定
全台を指定（スケジュールで実行する場合のみ）

配布を実行する際に SSM エージェントが実行した内容を S3 や CloudWatch Logs に出力することが可能ですが、そのために必要な権限は、インスタンスに適用された IAM ロールで定義されている必要があります。

SSM ドキュメント

SSM ドキュメントは、マネージドインスタンスで Systems Manager が実行するアクションを定義する JSON または YAML 形式のドキュメントです。

複数のタイプが存在し、それぞれ使用される Systems Manager の機能が異なります。

コマンドドキュメント
オートメーションドキュメント
パッケードキュメント
セッションドキュメント
ポリシードキュメント
Change Calendar ドキュメント

AWS Systems Manager ドキュメント - AWS Systems Manager

ディストリビューターによる配布においては、パッケージドキュメントとコマンドドキュメントが関連します。

パッケージドキュメント

パッケージドキュメントは、インストール可能なソフトウェア、アセットや、インストールを実行するスクリプトなどをパッケージ化したものです。

ディストリビューターにおいてはメインとなるコンポーネントと言えるでしょう。ここで定義した内容が、後続で説明する機能によってマネージドインスタンスに届けられ、インストール・更新などが実行されることになります。

パッケージドキュメントは AWS が提供しているものがあるほか、カスタマーが独自に作成することもできます。作成する場合の手順については以下のエントリに書きましたので、あわせてご参照ください。

コマンドドキュメント

コマンドドキュメントは、Run Command やステートマネージャーによってマネージドインスタンスに対して実行が命令されるコマンドの内容を定義したドキュメントです。

こちらも AWS が管理するものとカスタマーが作成できるものに分かれますが、ディストリビューターに関連するものは AWS が管理する AWS-ConfigureAWSPackage というドキュメントです。

こちらのドキュメントの内訳はこのようになっています。

{
  "schemaVersion": "2.0",
  "description": "Install or uninstall a Distributor package. You can install the latest version, default version, or a version of the package you specify. Packages provided by AWS such as AmazonCloudWatchAgent, AwsEnaNetworkDriver, and AWSPVDriver are also supported.",
  "parameters": {
    "action": {
      "description": "(Required) Specify whether or not to install or uninstall the package.",
      "type": "String",
      "allowedValues": [
        "Install",
        "Uninstall"
      ]
    },
    "installationType": {
      "description": "(Optional) Specify the type of installation. Uninstall and reinstall: The application is taken offline until the reinstallation process completes. In-place update: The application is available while new or updated files are added to the installation.",
      "type": "String",
      "allowedValues": [
        "Uninstall and reinstall",
        "In-place update"
      ],
      "default": "Uninstall and reinstall"
    },
    "name": {
      "description": "(Required) The package to install/uninstall.",
      "type": "String",
      "allowedPattern": "^arn:[a-z0-9][-.a-z0-9]{0,62}:[a-z0-9][-.a-z0-9]{0,62}:([a-z0-9][-.a-z0-9]{0,62})?:([a-z0-9][-.a-z0-9]{0,62})?:(package|document)\\/[a-zA-Z0-9/:.\\-_]{1,128}$|^[a-zA-Z0-9/:.\\-_]{1,128}$"
    },
    "version": {
      "description": "(Optional) The version of the package to install or uninstall. If you don’t specify a version, the system installs the latest published version by default. The system will only attempt to uninstall the version that is currently installed. If no version of the package is installed, the system returns an error.",
      "type": "String",
      "default": ""
    }
  },
  "mainSteps": [
    {
      "action": "aws:configurePackage",
      "name": "configurePackage",
      "inputs": {
        "name": "{{ name }}",
        "action": "{{ action }}",
        "installationType": "{{installationType}}",
        "version": "{{ version }}"
      }
    }
  ]
}

パラメータとして幾つかの値を引き渡す必要があり、その内容に応じてディストリビューターによる配布を行なった際の挙動が変わります。

名前	必須/オプション	概要
action	必須	インストールを行うかアンインストールを行うか
InstallationType	オプション	更新の手法についてアンインストールして再インストールするかインプレースでアップデートするか
name	必須	配布するパッケージドキュメント名
version	オプション	パッケージドキュメント内のアセットに複数のバージョンがあった場合どれを適用するか

コマンドドキュメント AWS-ConfigureAWSPackage に引き渡されたパラメータによって、どのパッケージドキュメントのどういった内容をどう適用するかが定義されている、という立て付けになります。

Run Command

Run Command によって、マネージドインスタンスに対してコマンドドキュメントを実行することができます。

ディストリビューターを1回限りで実行する際には、この Run Command を使用することになります。

実行の際には以下の項目を指定することができます。

Systems Manager Run Command を使用するコマンドの実行 - AWS Systems Manager

ドキュメント
- 先述の通り、 AWS-ConfigureAWSPackage です
パラメータ
- 先ほど確認した通りです
- パッケージドキュメントの指定はここで行います
ターゲット
- 以下の方式で指定することができます
  - 特定のタグが付与されたインスタンス
  - インスタンスIDで直接指定
  - リソースグループ
コメント
- コマンドの実行履歴を参照する際に確認できるメモです
タイムアウト
- コマンド実行の全体が失敗するまでに待機する秒数です
レートの制御
- 同時実行
  - コマンドを同時実行するインスタンス数または割合です
- エラーのしきい値
  - コマンド全体を停止するエラー数のしきい値です
  - インスタンス数または割合で指定します
出力オプション
- コマンド出力先を指定します
  - S3 バケット
  - CloudWatch Logs ロググループ
SNS 通知
- コマンドの実行状態に関する通知を受け取れます
  - 進行中
  - 成功
  - 失敗
  - タイムアウト
  - キャンセル